IRIX Base Documentation 1998 November/IRIX 6.5.2 Base Documentation November 1998.img/usr/share/catman/a_man/cat7/pciba.z/pciba

Text File | 1998-10-20 | 18KB | 331 lines

PPPPCCCCIIIIBBBBAAAA((((7777MMMM))))                                                            PPPPCCCCIIIIBBBBAAAA((((7777MMMM))))



NNNNAAAAMMMMEEEE
     pciba - User level PCI Bus Adapter interface.

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     The _p_c_i_b_a interface provides a mechanism to access the PCI bus address
     spaces, route PCI interrupts, and obtain PCI addresses for DMA from user
     programs.  It is intended to provide a convenient mechanism for writing
     user level PCI device drivers.

   AAAAccccttttiiiivvvvaaaattttiiiinnnngggg tttthhhheeee ppppcccciiiibbbbaaaa ddddrrrriiiivvvveeeerrrr
     The device driver that provides _p_c_i_b_a services is a loadable device
     driver, which may or may not be automatically loaded during the boot of
     your system.  The simplest way to find out if this driver is active in
     your system is to check the list of currently registered device drivers:

          _%%%% _mmmm_llll _llll_iiii_ssss_tttt _|||| _gggg_rrrr_eeee_pppp _pppp_cccc_iiii_bbbb_aaaa

     If there is no output, then the driver is not present and must be loaded
     before use.  To load the driver:

          _#### _llll_bbbb_oooo_oooo_tttt _----_LLLL _pppp_cccc_iiii_bbbb_aaaa

     If the driver is not active for a while, the system will keep it
     registered but remove it from memory, reloading the driver when it is
     again needed.  You can explicitly remove the driver from the system:

          _#### _mmmm_llll _llll_iiii_ssss_tttt _|||| _aaaa_wwww_kkkk _''''_////_pppp_cccc_iiii_bbbb_aaaa_//// _{{{{ _pppp_rrrr_iiii_nnnn_tttt_ffff _""""_llll_bbbb_oooo_oooo_tttt _----_UUUU _%%%%_dddd_\\\\_nnnn_""""_,,,, _$$$$_2222_;;;; _}}}}_'''' _|||| _ssss_hhhh

   FFFFiiiinnnnddddiiiinnnngggg yyyyoooouuuurrrr ddddeeeevvvviiiicccceeee uuuunnnnddddeeeerrrr ////hhhhwwww
     When the system boots, it builds a graph of all devices within the
     system; later, that graph is made available as a filesystem at the _////_hhhh_wwww
     mount point.

     Knowing the PCI ID word from your device, you can find where it sits
     under _////_hhhh_wwww fairly quickly by looking in one central location. There is a
     directory

          _////_hhhh_wwww_////_...._iiii_dddd_////_pppp_cccc_iiii_////_I_D_W_O_R_D_////

     where IDWORD is replaced by the eight-digit hexidecimal value from the ID
     word.  For instance, look in the directory

          _////_hhhh_wwww_////_...._iiii_dddd_////_pppp_cccc_iiii_////_1111_0000_AAAA_9999_0000_0000_0000_3333_////

     to find all the instances of SGI's standard IOC3 chip, which uses VENDOR
     0x10A9 and DEVICE 0x0003.

     Inside this directory you will find symbolic links to the real locations
     within _////_hhhh_wwww where your device has been found.






                                                                        PPPPaaaaggggeeee 1111






PPPPCCCCIIIIBBBBAAAA((((7777MMMM))))                                                            PPPPCCCCIIIIBBBBAAAA((((7777MMMM))))



   IIIIOOOOCCCCTTTTLLLL SSSSeeeerrrrvvvviiiicccceeeessss
     Vertex _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////slot_////_cccc_oooo_nnnn_ffff_iiii_gggg supports the following ioctl commands:

          _PPPP_CCCC_IIII_IIII_OOOO_CCCC_CCCC_FFFF_GGGG_RRRR_DDDD(type, register) - read a config register
          _PPPP_CCCC_IIII_IIII_OOOO_CCCC_CCCC_FFFF_GGGG_WWWW_RRRR(type, register) - write a config register

          In these macros, type is the data type being moved around (generally
          char, short or int) and register is the byte offset within the
          configuration space, generally obtained by using a macro supplied
          from the _<<<<_ssss_yyyy_ssss_////_PPPP_CCCC_IIII_////_PPPP_CCCC_IIII______dddd_eeee_ffff_ssss_...._hhhh_>>>> header file.  Some registers that are
          commonly accessed are wrapped up into single macros:

          _PPPP_CCCC_IIII_IIII_OOOO_CCCC_GGGG_EEEE_TTTT_IIII_DDDD - read slot's PCI Identification register.
          _PPPP_CCCC_IIII_IIII_OOOO_CCCC_SSSS_EEEE_TTTT_CCCC_MMMM_DDDD - write slot's PCI Command register.
          _PPPP_CCCC_IIII_IIII_OOOO_CCCC_GGGG_EEEE_TTTT_RRRR_EEEE_VVVV - read slot's PCI Device Revision register.
          _PPPP_CCCC_IIII_IIII_OOOO_CCCC_GGGG_EEEE_TTTT_HHHH_TTTT_YYYY_PPPP_EEEE - read slot's PCI Device Header Type register
          _PPPP_CCCC_IIII_IIII_OOOO_CCCC_GGGG_EEEE_TTTT_BBBB_AAAA_SSSS_EEEE(n) - read slot's PCI BASE(n) register.

     Vertex _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////slot_////_dddd_mmmm_aaaa supports the following ioctl commands:

          _PPPP_CCCC_IIII_IIII_OOOO_CCCC_DDDD_MMMM_AAAA_AAAA_LLLL_LLLL_OOOO_CCCC - Allocate a buffer for User DMA.
          The parameter should be a pointer to a 64-bit variable containing
          either simply the size of the transfer, or the result of packing
          some PCIIO DMA flags with the size using the
          _PPPP_CCCC_IIII_IIII_OOOO_CCCC_DDDD_MMMM_AAAA_AAAA_LLLL_LLLL_OOOO_CCCC______RRRR_EEEE_QQQQ_UUUU_EEEE_SSSS_TTTT______PPPP_AAAA_CCCC_KKKK(flags, size) macro (which just places
          the flags in the upper 32 bits of the value). All blocks allocated
          with _PPPP_CCCC_IIII_IIII_OOOO_CCCC_DDDD_MMMM_AAAA_AAAA_LLLL_LLLL_OOOO_CCCC should be explicitly released with _PPPP_CCCC_IIII_IIII_OOOO_CCCC_DDDD_MMMM_AAAA_FFFF_RRRR_EEEE_EEEE
          before the device is closed, after making sure that there is no
          longer any outstanding DMA to the target.

          _PPPP_CCCC_IIII_IIII_OOOO_CCCC_DDDD_MMMM_AAAA_FFFF_RRRR_EEEE_EEEE - Destroy a User DMA buffer.
          The parameter is a pointer to a 64-bit variable containing the PCI
          address of a DMA buffer previously allocated by a _PPPP_CCCC_IIII_IIII_OOOO_CCCC_DDDD_MMMM_AAAA_AAAA_LLLL_LLLL_OOOO_CCCC
          request.

     Vertex _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////slot_////_iiii_nnnn_tttt_rrrr supports the following ioctl commands:

          _PPPP_CCCC_IIII_IIII_OOOO_CCCC_SSSS_EEEE_TTTT_UUUU_LLLL_IIII(n) - set up a ULI
          The value n in the command is a bitmap of which interrupts are to be
          routed from the board, formed as the inclusive-or of one or more
          PCIIO_INTR_LINE macros.  The parameter is a pointer to a _ssss_tttt_rrrr_uuuu_cccc_tttt
          _uuuu_llll_iiii_aaaa_rrrr_gggg_ssss appropriately filled in.

   MMMMeeeemmmmoooorrrryyyy MMMMaaaappppppppiiiinnnngggg SSSSeeeerrrrvvvviiiicccceeeessss
     Memory mapping vertex _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////slot_////_bbbb_aaaa_ssss_eeee_////bar returns a pointer that
     can be used to initiate PIO access to the PCI space and offset that the
     system expects the PCI device in _s_l_o_t to decode with its BASE address
     register _b_a_r.  One such node is created for each BASE register that the
     system observes and sets up.






                                                                        PPPPaaaaggggeeee 2222






PPPPCCCCIIIIBBBBAAAA((((7777MMMM))))                                                            PPPPCCCCIIIIBBBBAAAA((((7777MMMM))))



     Memory mapping vertex _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////slot_////_mmmm_eeee_mmmm returns a pointer similar to
     the _b_a_r case above for the first BASE register that decodes PCI MEM
     space.  If no BASE registers on this device decode PCI MEM space, this
     vertex will not be present.

     Memory mapping vertex _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////slot_////_iiii_oooo returns a pointer similar to
     the _b_a_r case above for the first BASE register that decodes PCI I/O
     space.  If no BASE registers on this device decode PCI I/O space, this
     vertex will not be present.

     Memory mapping vertex _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////slot_////_rrrr_oooo_mmmm returns a pointer that can be
     used to initiate PIO access to the PCI space and offset that the system
     expects the PCI device in _s_l_o_t to decode with its Expansion Rom BASE
     address register.  If the card does not advertise an Expansion Rom, then
     this vertex will not be present.

     Memory mapping vertex _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////slot_////_dddd_mmmm_aaaa using as offset the PCI
     address retured by an _PPPP_CCCC_IIII_IIII_OOOO_CCCC_DDDD_MMMM_AAAA_AAAA_LLLL_LLLL_OOOO_CCCC ioctl command will provide an
     appropriate user mapping into the memory allocated for user-initiated
     DMA.  Any mmap request that does not precisely match the PCI address and
     size of an allocated User DMA block will fail.  Each such mmap call needs
     to be matched with a corresponding munmap call before the block is
     returned using _PPPP_CCCC_IIII_IIII_OOOO_CCCC_DDDD_MMMM_AAAA_FFFF_RRRR_EEEE_EEEE or the device is explicitly closed.

     Memory mapping vertex _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////_mmmm_eeee_mmmm provides a PIO pointer that
     resolves to any arbitrary location within the PCI MEM address space.

     Memory mapping vertex _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////_iiii_oooo provides a PIO pointer that resolves
     to any arbitrary location within the PCI I/O address space.

BBBBYYYYTTTTEEEE SSSSWWWWAAAAPPPPPPPPIIIINNNNGGGG IIIISSSSSSSSUUUUEEEESSSS
     MIPS processors and the PCI bus disagree on the relative significance of
     the individual bytes in a multiple-byte data item.  Like many modern RISC
     processors, the MIPS chips prefer to store the most significant byte at
     the first address in memory, with bytes of lower significance following
     it.  The PCI bus follows the convention that the lowest-numbered byte has
     the lowest significance, and it is followed by bytes in increasing
     significance order.

     The upshot of this is, hardware implementers have a choice over how to
     interconnect the byte lanes of the PCI bus to the byte lanes of the
     system native bus.  Do they connect them up by bits, so that data items
     the width of the PCI bus come across with the correct values, or do they
     connect them so that the address of each individual byte is invariant?

     In a configuration where 32-bit word values are preserved across the
     interface, the host processor must modify addresses for items smaller
     than a 32-bit word. Specifically, to access bytes, the address (or the
     byte offset from an aligned address, which is usually easier) must be
     XORed with 3, and to access 16-bit data, the address must be XORed with
     2.  SGI's PCI support codde gives this byte lane configuration the name
     WORD_VALUES.



                                                                        PPPPaaaaggggeeee 3333






PPPPCCCCIIIIBBBBAAAA((((7777MMMM))))                                                            PPPPCCCCIIIIBBBBAAAA((((7777MMMM))))



     In a configuration where each byte's address is precisely maintained,
     every data item is at its correct address; and, unless the device is one
     of the rare big-endian PCI devices, the bytes of any multibyte quantity
     are in reversed significance and must be reversed before storing or after
     reading.  SGI's PCI support codde gives this byte lane configuration the
     name BYTE_STREAM.

     When this driver is asked for mappings to devices, it provides mappings
     using WORD_VALUES, since it is more efficient to adjust the byte
     addresses of items than to swap bytes when accessing two and four byte
     quantities.

     There are currently no interfaces to pciba to request BYTE_STREAM
     mappings.

NNNNOOOOTTTTEEEESSSS
     If the system does not support ULI, the _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////slot_////_iiii_nnnn_tttt_rrrr vertex will
     not be present.

     If a boot prom allocates PCI space and sets up a device's BASE registers,
     and the values are not page aligned, pciba is unable to provide direct
     mmap service for those windows, and the corresponding
     _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////slot_////_bbbb_aaaa_ssss_eeee_////bar, _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////slot_////_mmmm_eeee_mmmm and _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////slot_////_iiii_oooo
     verticies will not exist.

     Such missing windows can still be accessed, as can any area decoded by a
     BASE register, by the longer method of using a _PPPP_CCCC_IIII_IIII_OOOO_CCCC_GGGG_EEEE_TTTT_BBBB_AAAA_SSSS_EEEE(n) ioctl
     command on the _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////slot_////_cccc_oooo_nnnn_ffff_iiii_gggg vertex to get the content of the
     BASE(n) register.  If this value is odd, mask off the last two bits and
     use the resulting value as the offset for mmap of the _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////_iiii_oooo
     vertex.  If the value was even, mask off the last four bits and use the
     resulting value as the offset for mmap of the _////_hhhh_wwww_////..._////_pppp_cccc_iiii_////_mmmm_eeee_mmmm vertex.

   CCCChhhhaaaannnnggggeeeessss ffffrrrroooommmm tttthhhheeee uuuussssrrrrppppcccciiii ddddrrrriiiivvvveeeerrrr
     The most obvious change from the _uuuu_ssss_rrrr_pppp_cccc_iiii driver is that the location of
     nodes in the hardware graph have changed.  A device on an IRIX 6.4 or
     older system that could be accessed using:

          _////_hhhh_wwww_////_mmmm_oooo_dddd_uuuu_llll_eeee_////_...._...._...._...._////_pppp_cccc_iiii_////_<<<<_ssss_llll_oooo_tttt_>>>>_////_uuuu_ssss_rrrr_pppp_cccc_iiii

     will now be found at:

          _////_hhhh_wwww_////_mmmm_oooo_dddd_uuuu_llll_eeee_////_...._...._...._...._////_pppp_cccc_iiii_////_<<<<_ssss_llll_oooo_tttt_>>>>

     The _mmmm_eeee_mmmm_3333_2222 and _mmmm_eeee_mmmm_6666_4444 nodes have been renamed _mmmm_eeee_mmmm.

     The map size in the usrpci driver was either a big or little window space
     (16 or 128 MB) but the pciba interface checks the size argument to the
     mmap call against the addressable size set up by the card in the Base
     Address Register that defines a particular space.





                                                                        PPPPaaaaggggeeee 4444






PPPPCCCCIIIIBBBBAAAA((((7777MMMM))))                                                            PPPPCCCCIIIIBBBBAAAA((((7777MMMM))))























































                                                                        PPPPaaaaggggeeee 5555